docs: clarify APM's role for skills, unify plugins-as-packages, add ADO sub-path examples, state stability by danielmeppiel · Pull Request #1127 · microsoft/apm

danielmeppiel · 2026-05-04T10:06:22Z

TL;DR

A user audited our docs against actual behavior and surfaced six high-signal gaps. This PR ships all six in a single doc-only change. A separate parser-fix issue tracks the one underlying bug we found while validating the ADO write-up (full https URL with sub-path).

Why

User feedback (verbatim quotes; full thread held privately):

"creating a package and initializing a project appear to be different concepts, yet in practice both are done via apm init... The documentation sometimes implies that a .apm/ directory is created as part of package creation, but in reality .apm/ is not generated by apm init."
"It's unclear how much value a SKILL.md provides beyond being another instruction file, and how authors should design them differently."
3a. "The documentation states that plugins can be used 'instead of' packages... Are plugins simply an alternative distribution format, or do they have strategic advantages over packages?"
3b. "There is no documented mechanism explaining how such users are expected to load or activate the plugin after extraction... no native loader outside APM."
"The dependencies guide mentions support for git URL + path + ref, including Azure DevOps repositories. I tested this with our ADO repo but could not get it to work (failed)."
"How stable and recommended is this feature today?" (re: apm run / Copilot CLI runtime)

Maintainer reframings applied:

Skills authoring is agentskills.io's job, not ours; APM is the package manager for skills, not the spec.
A plugin is a package, a package is a plugin. apm pack defaults to plugin-compatible output. The "Three modes" framing in the docs was the bug.
Without APM, you give up the manifest, lockfile, governance, security scanning. Same trade-off as npx skills add vs apm install.
apm run is fully experimental, vendor-neutral, modeled on npx-for-npm, not currently prioritized.

What

File	Change
`guides/skills.md`	Reframe opening to defer SKILL.md authoring to agentskills.io. Fix the `apm init` tree (no `.apm/` is scaffolded). Replace emoji checkmarks with `[+]`/`[x]`.
`guides/plugins.md`	Drop "Three modes" table. State plainly: every package is plugin-compatible by default; the only choice is whether you keep an `apm.yml`.
`guides/pack-distribute.md`	New "Without APM: what you give up" section with comparison table and host-specific install paths.
`guides/dependencies.md`	Add ADO object-form sub-path + ref example with shorthand alternative; warn that the full `https://...repo/sub-path` URL form is rejected today.
`getting-started/authentication.md`	Add ADO shorthand sub-path + ref example.
`introduction/what-is-apm.md`	Add explicit Stability section: stable surface (install / lock / audit / pack / unpack / cross-runtime deploy) vs experimental (`apm run`, Cowork).

Validation

Tested ADO sub-path + ref combinations against DependencyReference.parse() and parse_from_dict() for all 8 URL shapes:
- Working: all shorthand forms (dev.azure.com/...[/sub-path][#ref]) and all object-form variants.
- Broken: https://dev.azure.com///_git// with or without #ref raises Invalid Azure DevOps repository path. Tracked in a separate issue with a failing test as repro.
All edits in docs/ only - no source or CI touched.
Encoding: only ASCII added; existing box-drawing in directory trees preserved (matches existing convention in docs/; the project encoding rule scopes Markdown to .github/).

How to test

git fetch origin docs/customer-feedback-clarifications
git checkout docs/customer-feedback-clarifications
cd docs && npm install && npm run dev
# Visit:
#   /guides/skills/                       (new opening + agentskills.io callout)
#   /guides/plugins/                      (no more 'Three modes' table)
#   /guides/pack-distribute/              ('Without APM: what you give up' section)
#   /guides/dependencies/                 (ADO sub-path example + parser warning)
#   /getting-started/authentication/      (ADO _git sub-path example)
#   /introduction/what-is-apm/            (Stability section above 'What's next')

Verify the user-cited contradictions are gone:

guides/skills.md no longer claims apm init creates .apm/.
guides/plugins.md no longer frames plugins as an alternative to packages.
guides/pack-distribute.md now answers "what happens for non-APM consumers."
guides/dependencies.md documents ADO sub-path + ref with the exact two forms that work today.

Trade-offs

Pruned the "AI-optimized meta-guide" marketing copy in guides/skills.md. We lose some aspirational framing but stop overlapping with what agentskills.io owns.
Kept the "Three modes" rewrite minimal in guides/plugins.md rather than restructuring the whole page; downstream sections (Overview, Installation, Examples) still reflect the old framing in places and can be tightened in a follow-up.
The ADO https://...sub-path warning links to the parser-fix issue but ships before the fix lands. We can drop the warning in a follow-up PR once the parser is fixed.

…DO sub-path examples, state stability Customer feedback audit: - guides/skills.md: defer SKILL.md authoring to agentskills.io as the canonical source; APM owns distribution and governance, not the spec. Replace marketing copy with concrete responsibilities. Fix the apm init tree (only writes apm.yml; never scaffolds .apm/). Replace emoji checkmarks/x with ASCII bracket form per encoding rule. - guides/plugins.md: drop the misleading 'Three modes' framing. A plugin is a package, a package is a plugin. apm pack now emits plugin-compatible bundles by default. The only authoring choice is whether to keep an apm.yml. - guides/pack-distribute.md: add 'Without APM: what you give up' section. Frame as a value tradeoff (npx vs npm), not a doc gap. Cover the consumer install path for Claude Code and other hosts. - guides/dependencies.md, getting-started/authentication.md: add ADO sub-path + ref examples in shorthand and object form. Note the failing https://...repo/sub-path URL form (parser bug, tracked separately). - introduction/what-is-apm.md: explicit Stability section. State apm run / apm runtime as experimental, vendor-neutral (npx-for-npm analog), not currently prioritized. Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>

Section was renamed to 'Authoring workflow' in this PR; update the self-link in plugins.md and the cross-link from anatomy-of-an-apm-package.md to the new slug. Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>

Copilot

Pull request overview

Doc-only update that responds to customer-reported documentation gaps by clarifying APM's role (package manager vs skill spec), unifying the plugins-as-packages story, documenting Azure DevOps sub-path usage, and explicitly labeling stable vs experimental surfaces.

Changes:

Reframe skills docs to defer SKILL.md authoring guidance to agentskills.io and correct apm init scaffolding expectations.
Clarify that plugins and packages are the same artifact in APM, and add a “Without APM” consumer trade-off section for plugin bundles.
Add Azure DevOps sub-path + ref examples (and document the currently-broken full-https://.../<sub-path> URL shape) plus a Stability section in the intro docs.

Show a summary per file

File	Description
docs/src/content/docs/introduction/what-is-apm.md	Adds a Stability section distinguishing stable vs experimental CLI/integrations.
docs/src/content/docs/guides/skills.md	Reframes skills positioning, corrects `apm init` output tree, replaces emoji markers with ASCII status tokens.
docs/src/content/docs/guides/plugins.md	Removes “three modes” framing and states plugins/packages are the same artifact with `apm.yml` as the main authoring choice.
docs/src/content/docs/guides/pack-distribute.md	Adds “Without APM: what you give up” section describing consumer trade-offs and host placement notes.
docs/src/content/docs/guides/dependencies.md	Adds Azure DevOps object-form sub-path + ref example and a note documenting the unsupported full-URL-with-sub-path form.
docs/src/content/docs/getting-started/authentication.md	Adds Azure DevOps `_git` sub-path + ref install example.

Copilot's findings

Files reviewed: 7/7 changed files
Comments generated: 3

Co-authored-by: Copilot Autofix powered by AI <175728472+Copilot@users.noreply.github.com>

Roll forward the four PRs merged since v0.12.1: - #1137 feat(audit): default-on integration drift detection - #1135 fix(deps): subdir-agnostic bare cache (parallel sparse-checkout race) also resolves duplicate report #1140 (ADO sub-path manifestation) - #1129 docs: first-package guide accuracy (includes: auto, skill paths) - #1127 docs: APM's role for skills, plugins-as-packages, ADO sub-paths Bump pyproject.toml + uv.lock 0.12.1 -> 0.12.2 and convert the Unreleased CHANGELOG block into the 0.12.2 section, with a single 'so what' line per merged PR per the changelog contract. Co-authored-by: Daniel Meppiel <copilot-rework@github.com> Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>

Copilot AI review requested due to automatic review settings May 4, 2026 10:06

danielmeppiel requested a review from sergio-sisternes-epam as a code owner May 4, 2026 10:06

danielmeppiel mentioned this pull request May 4, 2026

ADO: full https:// URL with sub-path rejected by parser (shorthand and object form work) #1128

Open

Copilot started reviewing on behalf of danielmeppiel May 4, 2026 10:07 View session

docs: fix stale #hybrid-authoring-workflow anchors

fe8f554

Section was renamed to 'Authoring workflow' in this PR; update the self-link in plugins.md and the cross-link from anatomy-of-an-apm-package.md to the new slug. Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>

Copilot AI reviewed May 4, 2026

View reviewed changes

Comment thread docs/src/content/docs/introduction/what-is-apm.md Outdated

Comment thread docs/src/content/docs/guides/skills.md Outdated

Comment thread docs/src/content/docs/guides/dependencies.md Outdated

danielmeppiel and others added 3 commits May 4, 2026 12:17

Potential fix for pull request finding

358d58a

Co-authored-by: Copilot Autofix powered by AI <175728472+Copilot@users.noreply.github.com>

Potential fix for pull request finding

c072ac1

Co-authored-by: Copilot Autofix powered by AI <175728472+Copilot@users.noreply.github.com>

Potential fix for pull request finding

4d8d5db

Co-authored-by: Copilot Autofix powered by AI <175728472+Copilot@users.noreply.github.com>

danielmeppiel merged commit 8d381bf into main May 4, 2026
11 checks passed

danielmeppiel deleted the docs/customer-feedback-clarifications branch May 4, 2026 10:23

This was referenced May 4, 2026

docs: fix first-package guide (includes: auto explained, correct skill paths) #1129

Merged

[docs] Update documentation for features from 2026-05-04 #1132

Open

chore(release): v0.12.2 #1141

Merged

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

docs: clarify APM's role for skills, unify plugins-as-packages, add ADO sub-path examples, state stability#1127

docs: clarify APM's role for skills, unify plugins-as-packages, add ADO sub-path examples, state stability#1127
danielmeppiel merged 5 commits intomainfrom
docs/customer-feedback-clarifications

danielmeppiel commented May 4, 2026 •

edited

Loading

Uh oh!

Copilot AI left a comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants

Conversation

danielmeppiel commented May 4, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

TL;DR

Why

What

Validation

How to test

Trade-offs

Related

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Pull request overview

Copilot's findings

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants

danielmeppiel commented May 4, 2026 •

edited

Loading